<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<link rel="Stylesheet" type="text/css" href="doc.css" />
<title>Binding Constraints to Applications</title>
</head>
<body>
<h1><a name="top">Binding Constraints to Applications</a></h1>
<p>
With <a href="staticProviders.html">static</a> and <a href="dynamicProviders.html">dynamic</a>
constraint providers populating the EMF Validation Framework with a vast library of
constraints for some selection of models, how does an application actually select the
constraints that it needs to get its job done?  Other applications in the same Eclipse
environment may well contribute constraints that contradict its requirements.
</p><p>
Constraint bindings are intended to answer this need.  On the
<a href="../extension-points/org_eclipse_emf_validation_constraintBindings.html">org.eclipse.emf.validation.constraintBindings</a>
extension point, an application can define a <em class="UILabel">client context</em> that
identifies objects that it owns, and bind to it the constraints that it needs, either
individually or by category.  Validation operations, then, will only evaluate the
constraints that are bound to the client context(s) matching any individual object.
</p>

<h2>Client Context Selectors</h2>
<p>
The definition of a client context is determined by a condition that selects the elements
that belong to it.  This may be specified either using an XML enablement expression
(from the <em class="CodeName">org.eclipse.core.expressions</em> API) or by an implementation
of the <a href="../javadoc/org/eclipse/emf/validation/model/IClientSelector.html"><em class="CodeName">IClientSelector</em></a>
interface.
</p>

<blockquote>
	<img src="images/clientSelector.png" alt="Client Context Selector API"/><br/>
	<font size="-2">[<a href="images/clientSelector.svg">as SVG</a>]</font>
</blockquote>

<p>
The client selector simply computes a <em class="CodeName">true</em> result if and only if
it recognizes an object.  This may apply conditions on the state of the object, the content
type of the resource that it is in, or anything else.  For the XML enablement expressions,
the EMF Validation Framework does not supply any <em class="CodeName">&lt;with&gt;</em>
or <em class="CodeName">&lt;resolve&gt;</em> variables.  However, any property testers
defined for model elements are available to assist in constructing the selector condition.
</p>
<pre class="Code">
   &lt;extension
         point="<b>org.eclipse.emf.validation.constraintBindings</b>"&gt;
      &lt;<b>clientContext</b>
            default="false"
            id="org.eclipse.example.libraryContext"&gt;
         &lt;<b>enablement</b>&gt;
            &lt;test property="org.eclipse.example.resourceType" value="extlibrary"/&gt;
         &lt;/enablement&gt;
      &lt;/clientContext&gt;
   &lt;/extension&gt;
</pre>
<p>
The example above uses an hypothetical "resource type" property tester to check that an
element is contained in an EXTLibrary resource.  Because this kind of computation can be
expensive, the EMF Validation Framework only computes the client context of
<em class="UILabel">traveral roots</em>, assuming that any objects reached from a root
during the traversal is in the same client context.  By default, batch validation
traverses the entire content tree of every object in the initial selection, the traversal
roots.  See the <a href="traversal.html">Traversal Strategies</a> topic for details of how to
customize the batch validator's discovery of elements to validate.
</p>

<h2>Binding Constraints to a Client Context</h2>
<p>
Having defined a client context, constraints are bound to it by ID.  This can be done in
the same extension as that which defines the client context, or in a different extension,
even in a different plug-in.  Constraints can be bound by category or individually, or in
a mixture of the two.  Category bindings recursively include all nested categories.  This
is particularly useful for dynamic constraint providers, where one or more categories may
be statically defined and nested categories created and populated at run-time.
</p>
<pre class="Code">
   &lt;extension
         point="<b>org.eclipse.emf.validation.constraintBindings</b>"&gt;
      &lt;!-- Simple binding to a single category --&gt;
      &lt;<b>binding</b>
            <b>context</b>="org.eclipse.example.libraryContext"
            <b>category</b>="org.eclipse.example.library" /&gt;

      &lt;!-- Simple binding to a single constraint --&gt;
      &lt;binding
            context="org.eclipse.example.libraryContext"
            <b>constraint</b>="org.eclipse.example.library.LibraryNameIsUnique" /&gt;

      &lt;!-- Simple binding to a mixture of categories and constraints --&gt;
      &lt;binding
            context="org.eclipse.example.libraryContext"&gt;
         &lt;<b>category</b> ref="org.eclipse.example.library/bookConstraints" /&gt;
         &lt;<b>category</b> ref="org.eclipse.example.library/writerConstraints" /&gt;
         &lt;<b>constraint</b> ref="org.eclipse.example.library.borrowerOverdueFines" /&gt;
      &lt;/binding&gt;
   &lt;/extension&gt;
</pre>

<hr/>
<p>
<a href="https://www.eclipse.org/legal/epl-2.0/">Copyright (c) 2000, 2007 IBM Corporation and others.</a>
</p>
</body>
</html>
